.\" $Id: PAPI_start_counters.3,v 1.12 2004/10/04 02:16:25 jthomas Exp $
.TH PAPI_start_counters 3 "September, 2004" "PAPI Programmer's Reference" "PAPI"

.SH NAME
PAPI_start_counters \- PAPI High Level: start counting hardware events

.SH SYNOPSIS
.B C Interface
.nf
.B #include <papi.h>
.BI "int\ PAPI_start_counters(int *" events ", int " array_len ");"
.fi
.B Fortran Interface
.nf
.B #include "fpapi.h"
.BI PAPIF_start_counters(C_INT(*)\  events,\  C_INT\  array_len,\  C_INT\  check )
.fi

.SH DESCRIPTION
.B PAPI_start_counters(\|)
starts counting the events named in the events array.  This function
cannot be called if the events array is already running. The user must
call PAPI_stop_counters to stop the events explicitly if he/she wants to 
call this function again.  It is the user's responsibility
to choose events that can be counted simultaneously by reading the
vendor's documentation.  The length of the event array should be no longer
than the value returned by
.BR PAPI_num_counters(3).

.SH ARGUMENTS
.I *events 
-- an array of codes for events such as PAPI_INT_INS or a native event code
.LP
.I array_len 
-- the number of items in the *events array

.SH RETURN VALUES
On success, this function returns
.B "PAPI_OK."
 On error, a non-zero error code is returned.

.SH ERRORS
.TP
.B "PAPI_EINVAL"
One or more of the arguments is invalid.
.TP
.B "PAPI_EISRUN"
Counters already been started, you must call PAPI_stop_counters before
you call this function again.
.TP
.B "PAPI_ESYS"
A system or C library call failed inside PAPI, see the 
.I "errno"
variable.
.TP
.B "PAPI_ENOMEM"
Insufficient memory to complete the operation.
.TP
.B "PAPI_ECNFLCT"
The underlying counter hardware can not count this event and other events
in the EventSet simultaneously.
.TP
.B "PAPI_ENOEVNT"
The PAPI preset is not available on the underlying hardware. 

.SH EXAMPLES
.nf
.if t .ft CW
  /* Start counting events */
  if (PAPI_start_counters(Events, num_hwcntrs) != PAPI_OK)
    handle_error(1);
.if t .ft CW
.fi

.SH BUGS
This function has no known bugs.

.SH SEE ALSO
.BR PAPI_create_eventset "(3),"
.BR PAPI_add_event "(3),"
.BR PAPI_stop_counters "(3),"
.BR PAPI "(3),"
.BR PAPIF "(3)"
